/*
 * JSFunction.java - ScriptME
 * 
 * Copyright (c) 2009 Cesar Henriques <cesar at alttab.com.ar>.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the GNU Lesser Public License v2.1
 * which accompanies this distribution, and is available at
 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 * 
 * Based on FESI Project
 * 
 * Contributors:
 * 	Jean-Marc Lugrin - initial API and implementation
 * 	Cesar Henriques <cesar at alttab.com.ar> - J2ME Porting and Extensions
 */
package org.scriptme.ecmascript.jslib;

/**
 * Interface that an object must implement to be considered an EcmaScript
 * function.
 * <P>
 * This interface may be implemented by an object which will then be recognized
 * as a function or a constructor if used in EcmaScript.
 * <P>
 * Non function objects need not implement any specific interface, FESI using
 * introspection to discover their properties.
 * <P>
 * The parameters passed to the doCall or doNew arguments are transformed as
 * follow: <BR>
 * If they are FESI objects they are wrapped as JSObjects. <BR>
 * If they are FESI primitive, the corresponding most primitive java object is
 * used (for example Integer). <BR>
 * Otherwise (native objects) they are passed as native objects.
 * <P>
 * 
 * @see FESI.jslib.JSFunctionAdapter
 */
public interface JSFunction {

	/**
	 * Call the specified EcmaScript method of this object.
	 * 
	 * @param thisObject
	 *            the this object
	 * @param args
	 *            the args
	 * 
	 * @return The result of the evaluation
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object doCall(JSObject thisObject, Object args[])
			throws JSException;

	/**
	 * Create a new object, using the specified EcmaScript method of this
	 * object.
	 * 
	 * @param thisObject
	 *            the this object
	 * @param args
	 *            the args
	 * 
	 * @return The result of the evaluation
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object doNew(JSObject thisObject, Object args[])
			throws JSException;
}
